You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
bun-types: declare the name of each Bun.embeddedFiles entry - #48483
blob.name on an entry of Bun.embeddedFiles is error TS2339: Property 'name' does not exist on type 'Blob'. Two samples of docs/compiler/executables.mdx read it (lines 1016 and 1042).
The declaration is ReadonlyArray<Blob> (packages/bun-types/bun.d.ts:5198). Blob declares no name.
Fix
Declare ReadonlyArray<Blob & { readonly name: string }>, and show that type on the page.
Correct: in an executable from bun build --compile (canary 98cda0d), each entry is a Blob, not a File, and typeof blob.name is "string". template_blob sets the name from the embedded path (src/runtime/api/standalone_graph_jsc.rs:64). Both samples run as written.
Verified: test/integration/bun-types/fixture/bun.ts (the new lines report TS2339 and TS2578 with the declaration of main). bun test test/integration/bun-types/bun-types.test.ts: 30 pass.
Background
Bun.embeddedFiles lists the files that a standalone executable embeds, for example an import with { type: "file" }.
A Blob has no name in the types, and new Blob(["x"]).name is undefined at runtime.
Considered BunFile: it promises writer() and unlink(), which throw for an embedded file, and stat(), which resolves to undefined. Considered File: blob instanceof File is false.
Downsides
A plain Blob no longer fits where an entry is expected: const one: (typeof Bun.embeddedFiles)[number] = new Blob(["x"]) is TS2322. 3 of 15 usage shapes that compile on main fail. One is a // @ts-expect-error above blob.name, which is now unused.
blob.name = "x" works at runtime. It is TS2540 now, and TS2339 on main.
builtin_sources.bin grows 6 bytes and the package tarball 82 bytes.
Notes
Origin. The type check of the docs code blocks in #48479 found the two samples. With this change, that check reports nothing for the two samples and for the type listing of the page. If #48479 lands first, this pull request also removes those three entries of docs/compiler/executables.mdx from docs-samples.inventory.json.
Runtime probe (canary 1.4.4-canary.1+98cda0d8b, Linux x64). index.ts imports ./icon.png, ./data.json and ./template.html with { type: "file" }, then prints each entry of embeddedFiles. Built with bun build --compile ./index.ts --outfile ./app:
Run with bun index.ts, the array is empty. On an entry, writer() and unlink() throw ERR_INVALID_ARG_TYPE ("Cannot write to a Blob backed by bytes, which are always read-only"), await stat() is undefined, and await exists() is true. The second sample of the page (static routes from the embedded files) answers 200 for /favicon.ico, /logo.png and /styles.css and 404 for another path.
Why name is always a string.template_blob sets the blob's name to display_name(), the embedded path without /$bunfs/root/. The name getter of Blob returns that string (src/runtime/webcore/Blob.rs:1753).
readonly.BunFile.name and the File.name of the web platform are read-only in the types. The setter of Blob.prototype.name exists at runtime today. #32434 proposes to move name to File.prototype.
Measurements (TypeScript 6.0.2, the bun init tsconfig, main at 89452d2)
The two samples of docs/compiler/executables.mdx: TS2339 each on main, 0 diagnostics with this change. The type listing of the page was embeddedFiles: ReadonlyArray<Blob>;, which is TS2689 as a program. It is a declare const now, 0 diagnostics.
Usage shapes (22 small programs that use Bun.embeddedFiles): 15 compile on main, 3 of them fail with this change (the unused @ts-expect-error, a plain Blob assigned to the element type, a plain Blob pushed into a copy of the array). 4 that fail on main compile with this change.
bun.d.ts without comments: 85,099 to 85,127 bytes. Its zstd frame in builtin_sources.bin: 16,805 to 16,811 bytes (the parameters of src/codegen/builtins-manifest.ts).
bun pm pack of packages/bun-types: 82 bytes more (1,522,674 to 1,522,756, measured at 2596ac5).
Per type-check program that loads bun-types: +6 nodes, +2 symbols, +0 types (of 250,318 nodes).
The same program with lib.dom: covered by the checks with lib.dom.d.ts case of the test.
no test proof · iteration 0 · no src or test change; test-proof not applicable
Each entry of Bun.embeddedFiles is a Blob whose `name` is the name of the
embedded file. The declaration was ReadonlyArray<Blob>, and Blob has no
`name`, so `blob.name` in the two samples of docs/compiler/executables.mdx
was TS2339.
How it was reproduced: blob.name on an entry of Bun.embeddedFiles is TS2339 with the bun init tsconfig and the types of main (89452d2). In an executable from bun build --compile (canary 98cda0d), each entry is a Blob whose name is a string. The two samples of docs/compiler/executables.mdx run as written.
No actionable comments were generated in the recent review.
Walkthrough
Bun.embeddedFiles is now documented and typed as a readonly array of Blob values with a readonly name property. Type assertions check the entry shape.
Changes
Embedded file name type
Layer / File(s)
Summary
Declare and validate embedded file entry type packages/bun-types/bun.d.ts, docs/compiler/executables.mdx, test/integration/bun-types/fixture/bun.ts
The public type and documentation add a readonly name property to each embedded file Blob. Type assertions check that entries have a string name, extend Blob, and reject a plain Blob as an entry.
Possibly related PRs
oven-sh/bun#46007: Changes how --asset files are mounted in executable output, including their paths and basenames, which define the name covered by the new declaration.
oven-sh/bun#47895: Refactors get_embedded_files, which constructs the results described by the updated declaration.
Suggested reviewers: jarred-sumner
Merge Risk: Minimal · up to e907e
Embedded file names are now exposed in the public types. No merge-blocking issue was identified.
Pre-merge checks: 4
Check name
Status
Explanation
Title check
The title clearly identifies the change: adding the name property to each Bun.embeddedFiles entry.
Linked Issues check
Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check
Check skipped because no linked issues were found for this pull request.
Description check
The description is complete and relevant. It explains the problem, proposed fix, runtime behavior, tradeoffs, and verification results. It does not use the template headings exactly, but it provides t…
Full details: Description check
Explanation
The description is complete and relevant. It explains the problem, proposed fix, runtime behavior, tradeoffs, and verification results. It does not use the template headings exactly, but it provides the required information under equivalent sections.
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Reviewing files that changed from the base of the PR and between 89452d2 and e907ecd.
Files selected for processing: 3
docs/compiler/executables.mdx
packages/bun-types/bun.d.ts
test/integration/bun-types/fixture/bun.ts
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 1 remain after this review.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
Problem
blob.nameon an entry ofBun.embeddedFilesiserror TS2339: Property 'name' does not exist on type 'Blob'. Two samples ofdocs/compiler/executables.mdxread it (lines 1016 and 1042).ReadonlyArray<Blob>(packages/bun-types/bun.d.ts:5198).Blobdeclares noname.Fix
ReadonlyArray<Blob & { readonly name: string }>, and show that type on the page.bun build --compile(canary 98cda0d), each entry is aBlob, not aFile, andtypeof blob.nameis"string".template_blobsets the name from the embedded path (src/runtime/api/standalone_graph_jsc.rs:64). Both samples run as written.test/integration/bun-types/fixture/bun.ts(the new lines report TS2339 and TS2578 with the declaration of main).bun test test/integration/bun-types/bun-types.test.ts: 30 pass.Background
Bun.embeddedFileslists the files that a standalone executable embeds, for example an import with{ type: "file" }.Blobhas no name in the types, andnew Blob(["x"]).nameisundefinedat runtime.BunFile: it promiseswriter()andunlink(), which throw for an embedded file, andstat(), which resolves toundefined. ConsideredFile:blob instanceof Fileisfalse.Downsides
Blobno longer fits where an entry is expected:const one: (typeof Bun.embeddedFiles)[number] = new Blob(["x"])is TS2322. 3 of 15 usage shapes that compile on main fail. One is a// @ts-expect-erroraboveblob.name, which is now unused.blob.name = "x"works at runtime. It is TS2540 now, and TS2339 on main.builtin_sources.bingrows 6 bytes and the package tarball 82 bytes.Notes
Origin. The type check of the docs code blocks in #48479 found the two samples. With this change, that check reports nothing for the two samples and for the type listing of the page. If #48479 lands first, this pull request also removes those three entries of
docs/compiler/executables.mdxfromdocs-samples.inventory.json.Runtime probe (canary 1.4.4-canary.1+98cda0d8b, Linux x64).
index.tsimports./icon.png,./data.jsonand./template.htmlwith{ type: "file" }, then prints each entry ofembeddedFiles. Built withbun build --compile ./index.ts --outfile ./app:Run with
bun index.ts, the array is empty. On an entry,writer()andunlink()throwERR_INVALID_ARG_TYPE("Cannot write to a Blob backed by bytes, which are always read-only"),await stat()isundefined, andawait exists()istrue. The second sample of the page (static routes from the embedded files) answers 200 for/favicon.ico,/logo.pngand/styles.cssand 404 for another path.Why
nameis always a string.template_blobsets the blob's name todisplay_name(), the embedded path without/$bunfs/root/. Thenamegetter ofBlobreturns that string (src/runtime/webcore/Blob.rs:1753).readonly.BunFile.nameand theFile.nameof the web platform are read-only in the types. The setter ofBlob.prototype.nameexists at runtime today. #32434 proposes to movenametoFile.prototype.Measurements (TypeScript 6.0.2, the
bun inittsconfig, main at 89452d2)docs/compiler/executables.mdx: TS2339 each on main, 0 diagnostics with this change. The type listing of the page wasembeddedFiles: ReadonlyArray<Blob>;, which is TS2689 as a program. It is adeclare constnow, 0 diagnostics.Bun.embeddedFiles): 15 compile on main, 3 of them fail with this change (the unused@ts-expect-error, a plainBlobassigned to the element type, a plainBlobpushed into a copy of the array). 4 that fail on main compile with this change.bun.d.tswithout comments: 85,099 to 85,127 bytes. Its zstd frame inbuiltin_sources.bin: 16,805 to 16,811 bytes (the parameters ofsrc/codegen/builtins-manifest.ts).bun pm packofpackages/bun-types: 82 bytes more (1,522,674 to 1,522,756, measured at 2596ac5).lib.dom: covered by thechecks with lib.dom.d.tscase of the test.no test proof · iteration 0 · no src or test change; test-proof not applicable